home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / catD / pciio.z / pciio
Encoding:
Text File  |  1998-10-30  |  10.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ppppcccciiiiiiiioooo((((DDDD3333))))                                                            ppppcccciiiiiiiioooo((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      pciio: pciio_driver_register, pciio_driver_unregister, pciio_iterate,
  10.      pciio_reset - control PCI driver infrastructure
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////PPPPCCCCIIII////ppppcccciiiiiiiioooo....hhhh>>>>
  14.  
  15.      iiiinnnntttt
  16.      ppppcccciiiiiiiioooo____ddddrrrriiiivvvveeeerrrr____rrrreeeeggggiiiisssstttteeeerrrr ((((
  17.           ppppcccciiiiiiiioooo____vvvveeeennnnddddoooorrrr____iiiidddd____tttt _v_e_n_d_o_r__i_d,,,,
  18.           ppppcccciiiiiiiioooo____ddddeeeevvvviiiicccceeee____iiiidddd____tttt _d_e_v_i_c_e__i_d,,,,
  19.           cccchhhhaaaarrrr ****_d_r_i_v_e_r__p_r_e_f_i_x,,,,
  20.           uuuunnnnssssiiiiggggnnnneeeedddd _f_l_a_g_s))));;;;
  21.  
  22.      vvvvooooiiiidddd
  23.      ppppcccciiiiiiiioooo____ddddrrrriiiivvvveeeerrrr____uuuunnnnrrrreeeeggggiiiisssstttteeeerrrr ((((cccchhhhaaaarrrr ****_d_r_i_v_e_r__p_r_e_f_i_x))));;;;
  24.  
  25.      vvvvooooiiiidddd
  26.      ppppcccciiiiiiiioooo____iiiitttteeeerrrraaaatttteeee ((((
  27.           cccchhhhaaaarrrr ****_d_r_i_v_e_r__p_r_e_f_i_x,,,,
  28.           ppppcccciiiiiiiioooo____iiiitttteeeerrrr____ffff ****_f_u_n_c))));;;;
  29.      vvvvooooiiiidddd
  30.      ppppcccciiiiiiiioooo____rrrreeeesssseeeetttt ((((vvvveeeerrrrtttteeeexxxx____hhhhddddllll____tttt _p_c_o_n_n))));;;;
  31.  
  32.    AAAArrrrgggguuuummmmeeeennnnttttssss
  33.      _v_e_n_d_o_r__i_d
  34.      _d_e_v_i_c_e__i_d   Values that the PCI device will present in its configuration
  35.                  space as its vendor and device ID codes.
  36.  
  37.      _d_r_i_v_e_r__p_r_e_f_i_x
  38.                  The prefix string for the driver's standard entry points as
  39.                  configured in /_v_a_r/_s_y_s_g_e_n/_s_y_s_t_e_m.  The infrastructure uses
  40.                  this prefix to locate the driver's cdevsw entry, in order to
  41.                  call the driver's attach and detach entry points.
  42.  
  43.      _f_l_a_g_s       Normally passed as zero.
  44.  
  45.      _f_u_n_c        Address of a function to be applied to each of the connection
  46.                  points attached by this driver.
  47.  
  48.      _p_c_o_n_n       is an appropriate PCI connection point.
  49.  
  50. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  51.      The PCI infrastructure is a package of kernel services used by drivers
  52.      for PCI devices to set up services for their devices.  These services
  53.      include:
  54.  
  55.      +o   Locating all instances of the device in the system (documented in
  56.          this page).
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ppppcccciiiiiiiioooo((((DDDD3333))))                                                            ppppcccciiiiiiiioooo((((DDDD3333))))
  71.  
  72.  
  73.  
  74.      +o   Manipulating the PCI configuration space for the device (see
  75.          _p_c_i_i_o__c_o_n_f_i_g(D3)).
  76.  
  77.      +o   Constructing physical addresses to use for PIO access to the device
  78.          (see _p_c_i_i_o__p_i_o(D3)).
  79.  
  80.      +o   Constructing PCI addresses for the device to use for DMA access to
  81.          memory (see _p_c_i_i_o__d_m_a(D3)).
  82.  
  83.      +o   Arranging for a function to be called when the device requests
  84.          interrupt service (see _p_c_i_i_o__i_n_t_r(D3)).
  85.  
  86.      +o   Arranging for a function to be called when an error occurs during PIO
  87.          to, or DMA from the device (see _p_c_i_i_o__e_r_r_o_r(D3)).
  88.  
  89.      +o   Accessing useful fields in some otherwise opaque data structures (see
  90.          _p_c_i_i_o__g_e_t(D3)).
  91.  
  92.    DDDDrrrriiiivvvveeeerrrr RRRReeeeggggiiiissssttttrrrraaaattttiiiioooonnnn
  93.      _p_c_i_i_o__d_r_i_v_e_r__r_e_g_i_s_t_e_r() is used by drivers to inform the infrastructure
  94.      that they are interested in all PCI devices designated by specified
  95.      device and vendor ID numbers.  The infrastructure associates the
  96.      specified ID numbers with the specified device driver prefix.  When a
  97.      device with these IDs is discovered, the infrastructure calls the attach
  98.      entry point with that driver prefix, passing the hardware graph
  99.      connection point vertex as the only parameter.  This _c_o_n_n_e_c_t_i_o_n _p_o_i_n_t is
  100.      used in most calls to the infrastructure to identify the PCI device of
  101.      interest.
  102.  
  103.      A loadable device driver calls _p_c_i_i_o__d_r_i_v_e_r__r_e_g_i_s_t_e_r() from its _r_e_g()
  104.      entry point.  A driver prelinked into the kernel should also make the
  105.      call from _r_e_g() for consistency, but may call from the _i_n_i_t() entry point
  106.      if necessary.
  107.  
  108.      Device drivers may make multiple calls with different vendor and device
  109.      ID numbers, representing several compatible PCI devices.
  110.  
  111.      Wildcard values PCIIO_VENDOR_ID_NONE and PCIIO_DEVICE_ID_NONE may be used
  112.      if cards from any vendor or cards with any device code are of supported.
  113.      When both vendor and device are wildcarded, the _a_t_t_a_c_h() routine is
  114.      called for every PCI device connected to the system.
  115.  
  116.      When a loadable device driver calls _p_c_i_i_o__d_r_i_v_e_r__r_e_g_i_s_t_e_r(), one or more
  117.      calls to the driver's _a_t_t_a_c_h() function can occur before the
  118.      infrastructure returns control to the caller.  On some large systems, the
  119.      _a_t_t_a_c_h() calls can be executed by other threads and possibly on other
  120.      processors, concurrently with continued execution of the _r_e_g() entry
  121.      point.
  122.  
  123.      _p_c_i_i_o__d_r_i_v_e_r__u_n_r_e_g_i_s_t_e_r() should be called by any unloadable device
  124.      driver, from within the driver's _u_n_r_e_g() entry point.  This will trigger
  125.      calls to the driver's _d_e_t_a_c_h() entry point, and remove the association
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ppppcccciiiiiiiioooo((((DDDD3333))))                                                            ppppcccciiiiiiiioooo((((DDDD3333))))
  137.  
  138.  
  139.  
  140.      between the driver and any vendor and device IDs.
  141.  
  142.    CCCCoooonnnnnnnneeeeccccttttiiiioooonnnn PPPPooooiiiinnnntttt IIIItttteeeerrrraaaattttiiiioooonnnn
  143.      It is sometimes important for driver code to be able to go back and
  144.      revisit each connection point that was passed to its _a_t_t_a_c_h() entry
  145.      point; for example to disconnect interrupt and error handling functions
  146.      before the driver unloads, or to reconnect these handlers after the
  147.      driver is reloaded.  _p_c_i_i_o__i_t_e_r_a_t_e() provides a quick mechanism to have a
  148.      private function called with each connection point that the
  149.      infrastructure has matched with the specified driver.
  150.  
  151.      On large systems, the calls to _f_u_n_c() can take place in multiple separate
  152.      threads on multiple processors, so the function must use appropriate
  153.      locking when accessing driver-global structures.
  154.  
  155.    RRRReeeesssseeeettttttttiiiinnnngggg aaaa PPPPCCCCIIII ccccaaaarrrrdddd
  156.      _p_c_i_i_o__r_e_s_e_t() is used to attempt to activate the PCI Reset line connected
  157.      to a specific card without affecting other devices on the PCI bus.  When
  158.      this can be done, the device is reset and basic configuration information
  159.      is reloaded.
  160.  
  161. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  162.      Here is how a typical driver might make use of these functions:
  163.  
  164.           static char    pcifoo_prefix[] = "pcifoo_";
  165.           static char    pcifoo_edge[] = "foo";
  166.           pcifoo_init(void)
  167.           {
  168.                /* the first time through, we are not
  169.                 * registered, so this is a no-op.
  170.                 * after that, it triggers reload_me.
  171.                 */
  172.                pciio_iterate(pcifoo_prefix, pcifoo_reload_me);
  173.           }
  174.           pcifoo_unload(void)
  175.           {
  176.                ...
  177.                pciio_iterate(pcifoo_prefix, pcifoo_unload_me);
  178.                ...
  179.           }
  180.           pcifoo_reg(void)
  181.           {
  182.                pciio_driver_register(
  183.                     PCIFOO_VENDOR_ID,
  184.                     PCIFOO_DEVICE_ID,
  185.                     pcifoo_prefix, 0);
  186.           }
  187.           pcifoo_unreg(void)
  188.           {
  189.                pciio_driver_unregister(pcifoo_prefix);
  190.           }
  191.           pcifoo_reload_me(vertex_hdl_t conn)
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ppppcccciiiiiiiioooo((((DDDD3333))))                                                            ppppcccciiiiiiiioooo((((DDDD3333))))
  203.  
  204.  
  205.  
  206.           {
  207.                vertex_hdl_t   vhdl;
  208.                pcifoo_soft_t  pcifoo_soft;
  209.                if (GRAPH_SUCCESS !=
  210.                     hwgraph_traverse(conn, pcifoo_edge, &vhdl))
  211.                          return;
  212.                pcifoo_soft = device_info_get(vhdl);
  213.                if (!pcifoo_soft)
  214.                     return;
  215.                if (pcifoo_soft->intr)
  216.                     pciio_intr_connect(
  217.                          pcifoo_soft->intr,
  218.                          pcifoo_intr,
  219.                          pcifoo_soft);
  220.           }
  221.           pcifoo_unload_me(vertex_hdl_t conn)
  222.           {
  223.                vertex_hdl_t   vhdl;
  224.                pcifoo_soft_t  pcifoo_soft;
  225.                if (GRAPH_SUCCESS !=
  226.                     hwgraph_traverse(conn, pcifoo_edge, &vhdl))
  227.                          return;
  228.                pcifoo_soft = device_info_get(vhdl);
  229.                if (pcifoo_soft->intr)
  230.                     pciio_intr_disconnect(pcifoo_soft->intr);
  231.           }
  232.  
  233.  
  234. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  235.      pciio_config(D3), pciio_dma(D3), pciio_error(D3), pciio_get(D3),
  236.      pciio_intr(D3), pciio_pio(D3).
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.